{literal}
<h2>What is a controller?</h2>

A Controller is simply a class file that is named in a way that can be associated with a URI.<br>
Consider this uri:<br>
<pre class="code">
http://site.com/article/
</pre>
This will search for file in application/controllers/Site/articleController.php.<br>
It expects that file contains class named ArticleController and it has method index() in it.

<h2>Sample controller - Hello world!</h2>
<pre class="code">
&lt;?php
class ArticleController extends DomController {
	
	public function index() {
		echo 'Hellow World!';
	}

}
?&gt;
</pre>
Notice that spelling of files must be correct!<br>
File name starts with not capitalized letter, while classname starts with capitalized letter!<br>

<h2>Methods</h2>
You can use custom methods in your controller like this:
<pre class="code">
&lt;?php
class ArticleController extends DomController {
	
	public function index() {
		
	}
	
	public function show_article( $id ) {
	
	}

}
?&gt;
</pre>
To open method show_article you should open url http://site.com/article/show_article/ID<br>
If you don't give ID you will see error 404 (Page not found) page. You can make controller method to get argument as optional (show_article( $id = NULL) ), then it will be called when ID is not given.


<h2>Defining default controller</h2>
You should open your index.php.<br>
<pre class="code">
&lt;?php
$site = new DomSite( SITE_URL, 'Site');
$site->setIndexController('Article'); // setting article controller as default.
$site->display();
?&gt;
</pre>
NB! Default controller is "Index" when setIndexController method is not called!



<h2>Remapping method calls</h2>
As url http://site.com/article/show_article/ID is a bit ugly, it would be better to use http://site.com/art/ID. <br>
This is possible with rewriting:
<pre class="code">
&lt;?php
$site = new DomSite( SITE_URL, 'Site');

// lets define one rewriting rule
$site-> setRewriteRules(array(
   'art' => array('article','show_article'),
)); 

$site->display();
?&gt;
</pre>
<br>
NB! You should not rewrite class names! <br>
Don't do this:
<pre class="code">
&lt;?php
$site-> setRewriteRules(array(
   'article' => array('article','show_article'),
)); 
?&gt;
</pre>
If you open URL <i>http://site.com/article/someMethod</i>, then <i>articleController-&gt;show_article( someMethod )</i> will be called. 
You might have expected it to call articleController-&gt;someMethod()<br>
<br>
When you really want to use "article" in remapping, you might think about putting controller name to plural (articlesController).


<h2>setup and finalize</h2>
There are two magic methods in controllers:<br>
1) Setup - Will be called before real method.<br>
Setup method is very useful to handle maybe login parameters or setting up some part of the site that is always same for this controller.<br>
<br>
2) Finialize - Will be called after real method.<br>
<br>
<pre class="code">
&lt;?php
class ArticleController extends DomController {
	
	public function index() {
		
	}
	
	public function show( ) {
		echo 'TWO ';
	}
	
	public function setup() {
		echo 'ONE ';
	}
	
	public function finalize() {
		echo 'THREE ';
	}

}
?&gt;
</pre>
Opening url http://site.com/Article/show/ would produce output ONE TWO THREE<br>
<br>

<h2>Communicating with other controllers</h2>

You can also call other controller methods by using loadController method.

<pre class="code">
&lt;?php
class IndexController extends DomController {
	
	public function index() {
		
	}
	
	public function setup() {
		$controller = $this->loadController('User')
		$controller->setup();
		
		// shorthand $this->loadController('User')->setup();
	}

}
?&gt;
</pre>
<pre class="code">
&lt;?php
class UserController extends DomController {
	
	public function index() {
		
	}
	
	public function setup() {
		// handle user logging etc...
	}

}
?&gt;
</pre>

<h2>Default setup and finalize</h2>
If custom controller does not have setup or finalize method then Index controller setup/finalize will be called!
<pre class="code">
&lt;?php
class IndexController extends DomController {
	
	public function index() {
		
	}
	
	public function setup() {
		echo 'SETUP';
	}

}
?&gt;
</pre>
<pre class="code">
&lt;?php
class UserController extends DomController {
	
	public function index() {
		
	}

}
?&gt;
</pre>
Now if we open URL http://site.com/Index/index/ "SETUP" will be outputted.<br>
If we open URL http://site.com/User/index/ "SETUP will ALSO be outputted.<br>
To disable this you need to add setup method to UserController.<br>



<h2>Making simple access rules</h2>
If you are using DomAuth/DomUser you can test if user is allowed to call some controller methods or not.<br>
DomUser uses DomArAcl plugin to manage rights.<br>
If user doesn't have enaugh rights error403 will be used.<br>
<pre class="code">
&lt;?php
class MyUser extends DomUser {

}

class UserController extends DomController {
	
	public function index() {
		
	}
	
	public function setup() {
		// Test if any user has logged in.
		$user = MyUser::getLoggedInUser();
		if( $user )
			// Set DomSite (And Controllers) that this is logged in user and his rights should be used.
			$this->getSite()->setUser( $user );
	}
	
	public function restrictedMethod() {
		$this->auth('accessRestrictedMethod');
		// If user does not have enaugh rights NotAuthorizedException is thrown and catched in DomController.
		
		// to allow user to access restricted method
		// $user->rights->allow('accessRestrictedMethod');
		 
	}
	
	public function needThisOrThat() {
		// using some simple logical statements;
		$this->auth('some=a|other=b&always');
		
		// this is same as this logical statment
		if( $some == 'a' or $other == 'b' && $always ) {
		
		}
		
		// to allow user to access this method you can do one of these
		// $user->rights->allow('some','a');
		// or 
		// $user->rights->allow('other','b');
		// AND
		// $user->rights->allow('always'); 
	}
	
	public function moreComplex() {
		if( !$this->getUser() or !$this->getUser()->rights->isAllowed('someRight') 
			or $this->getUser()->rights->getValue('anotherRight') != 10 ) {
			$this->error403();
			return;
		}
	}


}
?&gt;
</pre>


{/literal}